From cf707cbfaa06d8fb04f0873d49230adbb9947660 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Mon, 22 Feb 2021 17:35:39 +0000 Subject: [PATCH] expression: Update docs format And add documentation stanzas for GtkExpression sub-types. --- gtk/gtkexpression.c | 389 ++++++++++++++++++++++++-------------------- 1 file changed, 210 insertions(+), 179 deletions(-) diff --git a/gtk/gtkexpression.c b/gtk/gtkexpression.c index bbe19ad301..f565746529 100644 --- a/gtk/gtkexpression.c +++ b/gtk/gtkexpression.c @@ -36,9 +36,9 @@ * * An important aspect of expressions is that the value can be obtained * from a source that is several steps away. For example, an expression - * may describe ‘the value of property A of @object1, which is itself the - * value of a property of @object2’. And @object1 may not even exist yet - * at the time that the expression is created. This is contrast to GObject + * may describe ‘the value of property A of `object1`, which is itself the + * value of a property of `object2`’. And `object1` may not even exist yet + * at the time that the expression is created. This is contrast to `GObject` * property bindings, which can only create direct connections between * the properties of two objects that must both exist for the duration * of the binding. @@ -47,53 +47,56 @@ * refers to. An evaluation always happens in the context of a current object * called `this` (it mirrors the behavior of object-oriented languages), * which may or may not influence the result of the evaluation. Use - * gtk_expression_evaluate() for evaluating an expression. + * [method@Gtk.Expression.evaluate] for evaluating an expression. * * Various methods for defining expressions exist, from simple constants via - * gtk_constant_expression_new() to looking up properties in a #GObject (even - * recursively) via gtk_property_expression_new() or providing custom functions - * to transform and combine expressions via gtk_closure_expression_new(). + * [ctor@Gtk.ConstantExpression.new] to looking up properties in a `GObject` + * (even recursively) via [ctor@Gtk.PropertyExpression.new] or providing + * custom functions to transform and combine expressions via + * [ctor@Gtk.ClosureExpression.new]. * * Here is an example of a complex expression: - * |[ + * + * ```c * color_expr = gtk_property_expression_new (GTK_TYPE_LIST_ITEM, * NULL, "item"); * expression = gtk_property_expression_new (GTK_TYPE_COLOR, * color_expr, "name"); - * ]| + * ``` * - * when evaluated with `this` being a GtkListItem, it will obtain the - * "item" property from the GtkListItem, and then obtain the "name" property - * from the resulting object (which is assumed to be of type GTK_TYPE_COLOR). + * when evaluated with `this` being a `GtkListItem`, it will obtain the + * "item" property from the `GtkListItem`, and then obtain the "name" property + * from the resulting object (which is assumed to be of type `GTK_TYPE_COLOR`). * * A more concise way to describe this would be - * |[ + * + * ``` * this->item->name - * ]| + * ``` * * The most likely place where you will encounter expressions is in the context - * of list models and list widgets using them. For example, #GtkDropDown is - * evaluating a GtkExpression to obtain strings from the items in its model + * of list models and list widgets using them. For example, `GtkDropDown` is + * evaluating a `GtkExpression` to obtain strings from the items in its model * that it can then use to match against the contents of its search entry. - * #GtkStringFilter is using a GtkExpression for similar reasons. + * `GtkStringFilter` is using a `GtkExpression` for similar reasons. * * By default, expressions are not paying attention to changes and evaluation is * just a snapshot of the current state at a given time. To get informed about - * changes, an expression needs to be "watched" via a #GtkExpressionWatch, which - * will cause a callback to be called whenever the value of the expression may - * have changed. gtk_expression_watch() starts watching an expression, and - * gtk_expression_watch_unwatch() stops. + * changes, an expression needs to be "watched" via a [struct@Gtk.ExpressionWatch], + * which will cause a callback to be called whenever the value of the expression may + * have changed; [method@Gtk.Expression.watch] starts watching an expression, and + * [method@Gtk.ExpressionWatch.unwatch] stops. * * Watches can be created for automatically updating the property of an object, - * similar to GObject's #GBinding mechanism, by using gtk_expression_bind(). + * similar to GObject's `GBinding` mechanism, by using [method@Gtk.Expression.bind]. * - * # GtkExpression in GObject properties + * ## GtkExpression in GObject properties * - * In order to use a #GtkExpression as a #GObject property, you must use the - * gtk_param_spec_expression() when creating a #GParamSpec to install in the - * #GObject class being defined; for instance: + * In order to use a `GtkExpression` as a `GObject` property, you must use the + * [id@gtk_param_spec_expression] when creating a `GParamSpec` to install in the + * `GObject` class being defined; for instance: * - * |[ + * ```c * obj_props[PROP_EXPRESSION] = * gtk_param_spec_expression ("expression", * "Expression", @@ -101,14 +104,14 @@ * G_PARAM_READWRITE | * G_PARAM_STATIC_STRINGS | * G_PARAM_EXPLICIT_NOTIFY); - * ]| + * ``` * - * When implementing the #GObjectClass.set_property() and #GObjectClass.get_property() - * virtual functions, you must use gtk_value_get_expression(), to retrieve the - * stored #GtkExpression from the #GValue container, and gtk_value_set_expression(), - * to store the #GtkExpression into the #GValue; for instance: + * When implementing the `GObjectClass.set_property` and `GObjectClass.get_property` + * virtual functions, you must use [id@gtk_value_get_expression], to retrieve the + * stored `GtkExpression` from the `GValue` container, and [id@gtk_value_set_expression], + * to store the `GtkExpression` into the `GValue`; for instance: * - * |[ + * ```c * // in set_property()... * case PROP_EXPRESSION: * foo_widget_set_expression (foo, gtk_value_get_expression (value)); @@ -118,45 +121,44 @@ * case PROP_EXPRESSION: * gtk_value_set_expression (value, foo->expression); * break; - * ]| + * ``` * - * # GtkExpression in .ui files + * ## GtkExpression in .ui files * - * GtkBuilder has support for creating expressions. The syntax here can be used where - * a #GtkExpression object is needed like in a tag for an expression - * property, or in a tag to bind a property to an expression. + * `GtkBuilder` has support for creating expressions. The syntax here can be used where + * a `GtkExpression` object is needed like in a `` tag for an expression + * property, or in a `` tag to bind a property to an expression. * - * To create an property expression, use the element. It can have a `type` + * To create an property expression, use the `` element. It can have a `type` * attribute to specify the object type, and a `name` attribute to specify the property - * to look up. The content of can either be an element specfiying the expression + * to look up. The content of `` can either be an element specfiying the expression * to use the object, or a string that specifies the name of the object to use. * * Example: - * |[ + * + * ```xml * string_filter - * ]| + * ``` * - * To create a constant expression, use the element. If the type attribute + * To create a constant expression, use the `` element. If the type attribute * is specified, the element content is interpreted as a value of that type. Otherwise, - * it is assumed to be an object. + * it is assumed to be an object. For instance: * - * Example: - * |[ + * ```xml * string_filter * Hello, world - * ]| + * ``` * - * To create a closure expression, use the element. The `type` and `function` + * To create a closure expression, use the `` element. The `type` and `function` * attributes specify what function to use for the closure, the content of the element - * contains the expressions for the parameters. + * contains the expressions for the parameters. For instance: * - * Example: - * |[ + * ```xml * * File size: * myfile * - * ]| + * ``` */ @@ -222,6 +224,14 @@ struct _GtkExpressionTypeInfo GtkExpressionSubWatch *watch); }; +/** + * GtkExpressionWatch: + * + * An opaque structure representing a watched [class@Gtk.Expression]. + * + * The contents of `GtkExpressionWatch` should only be accessed through the + * provided API. + */ struct _GtkExpressionWatch { GtkExpression *expression; @@ -352,12 +362,12 @@ value_expression_lcopy_value (const GValue *value, /** * gtk_value_set_expression: - * @value: a #GValue initialized with type %GTK_TYPE_EXPRESSION - * @expression: a #GtkExpression + * @value: a `GValue` initialized with type `GTK_TYPE_EXPRESSION` + * @expression: a `GtkExpression` * - * Stores the given #GtkExpression inside @value. + * Stores the given `GtkExpression` inside `value`. * - * The #GValue will acquire a reference to the @expression. + * The `GValue` will acquire a reference to the `expression`. */ void gtk_value_set_expression (GValue *value, @@ -384,12 +394,12 @@ gtk_value_set_expression (GValue *value, /** * gtk_value_take_expression: - * @value: a #GValue initialized with type %GTK_TYPE_EXPRESSION - * @expression: (transfer full) (nullable): a #GtkExpression + * @value: a `GValue` initialized with type `GTK_TYPE_EXPRESSION` + * @expression: (transfer full) (nullable): a `GtkExpression` * - * Stores the given #GtkExpression inside @value. + * Stores the given `GtkExpression` inside `value`. * - * This function transfers the ownership of the @expression to the #GValue. + * This function transfers the ownership of the `expression` to the `GValue`. */ void gtk_value_take_expression (GValue *value, @@ -416,11 +426,11 @@ gtk_value_take_expression (GValue *value, /** * gtk_value_get_expression: - * @value: a #GValue initialized with type %GTK_TYPE_EXPRESSION + * @value: a `GValue` initialized with type `GTK_TYPE_EXPRESSION` * - * Retrieves the #GtkExpression stored inside the given @value. + * Retrieves the `GtkExpression` stored inside the given `value`. * - * Returns: (transfer none) (nullable): a #GtkExpression + * Returns: (transfer none) (nullable): a `GtkExpression` */ GtkExpression * gtk_value_get_expression (const GValue *value) @@ -432,12 +442,12 @@ gtk_value_get_expression (const GValue *value) /** * gtk_value_dup_expression: - * @value: a #GValue initialized with type %GTK_TYPE_EXPRESSION + * @value: a `GValue` initialized with type `GTK_TYPE_EXPRESSION` * - * Retrieves the #GtkExpression stored inside the given @value, and acquires + * Retrieves the `GtkExpression` stored inside the given `value`, and acquires * a reference to it. * - * Returns: (transfer full) (nullable): a #GtkExpression + * Returns: (transfer full) (nullable): a `GtkExpression` */ GtkExpression * gtk_value_dup_expression (const GValue *value) @@ -529,9 +539,9 @@ gtk_param_expression_get_type (void) * @blurb: a user-readable description of the property * @flags: flags for the property * - * Creates a new #GParamSpec instance for a property holding a #GtkExpression. + * Creates a new `GParamSpec` instance for a property holding a `GtkExpression`. * - * See g_param_spec_internal() for details on the property strings. + * See `g_param_spec_internal()` for details on the property strings. * * Returns: (transfer full): a newly created property specification */ @@ -707,7 +717,7 @@ gtk_expression_type_register_static (const char *type_name, * @expression_type: the type of expression to create * @value_type: the type of the value returned by this expression * - * Returns: (transfer full): the newly created #GtkExpression + * Returns: (transfer full): the newly created `GtkExpression` */ static gpointer gtk_expression_alloc (GType expression_type, @@ -743,8 +753,11 @@ gtk_expression_subwatch_finish (GtkExpression *self, /* {{{ GtkConstantExpression */ -typedef struct _GtkConstantExpression GtkConstantExpression; - +/** + * GtkConstantExpression: + * + * A constant value in a `GtkExpression`. + */ struct _GtkConstantExpression { GtkExpression parent; @@ -801,10 +814,10 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkConstantExpression, * @value_type: The type of the object * @...: arguments to create the object from * - * Creates a GtkExpression that evaluates to the + * Creates a `GtkExpression` that evaluates to the * object given by the arguments. * - * Returns: a new #GtkExpression + * Returns: (transfer full) (type GtkConstantExpression): a new `GtkExpression` */ GtkExpression * gtk_constant_expression_new (GType value_type, @@ -838,12 +851,12 @@ gtk_constant_expression_new (GType value_type, } /** - * gtk_constant_expression_new_for_value: - * @value: a #GValue + * gtk_constant_expression_new_for_value: (constructor) + * @value: a `GValue` * - * Creates an expression that always evaluates to the given @value. + * Creates an expression that always evaluates to the given `value`. * - * Returns: a new #GtkExpression + * Returns: (transfer full) (type GtkConstantExpression): a new `GtkExpression` **/ GtkExpression * gtk_constant_expression_new_for_value (const GValue *value) @@ -864,7 +877,7 @@ gtk_constant_expression_new_for_value (const GValue *value) /** * gtk_constant_expression_get_value: - * @expression: (type GtkConstantExpression): a constant #GtkExpression + * @expression: (type GtkConstantExpression): a constant `GtkExpression` * * Gets the value that a constant expression evaluates to. * @@ -884,9 +897,13 @@ gtk_constant_expression_get_value (GtkExpression *expression) /* {{{ GtkObjectExpression */ -typedef struct _GtkObjectExpression GtkObjectExpression; typedef struct _GtkObjectExpressionWatch GtkObjectExpressionWatch; +/** + * GtkObjectExpression: + * + * A `GObject` value in a `GtkExpression`. + */ struct _GtkObjectExpression { GtkExpression parent; @@ -999,16 +1016,18 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkObjectExpression, >k_object_expression_info) /** - * gtk_object_expression_new: + * gtk_object_expression_new: (constructor) * @object: (transfer none): object to watch * - * Creates an expression evaluating to the given @object with a weak reference. - * Once the @object is disposed, it will fail to evaluate. + * Creates an expression evaluating to the given `object` with a weak reference. + * + * Once the `object` is disposed, it will fail to evaluate. + * * This expression is meant to break reference cycles. * - * If you want to keep a reference to @object, use gtk_constant_expression_new(). + * If you want to keep a reference to `object`, use [ctor@Gtk.ConstantExpression.new]. * - * Returns: a new #GtkExpression + * Returns: (type GtkObjectExpression) (transfer full): a new `GtkExpression` **/ GtkExpression * gtk_object_expression_new (GObject *object) @@ -1029,11 +1048,11 @@ gtk_object_expression_new (GObject *object) /** * gtk_object_expression_get_object: - * @expression: (type GtkObjectExpression): an object #GtkExpression + * @expression: (type GtkObjectExpression): an object `GtkExpression` * * Gets the object that the expression evaluates to. * - * Returns: (transfer none) (nullable): the object, or %NULL + * Returns: (transfer none) (nullable): the object, or `NULL` */ GObject * gtk_object_expression_get_object (GtkExpression *expression) @@ -1049,8 +1068,11 @@ gtk_object_expression_get_object (GtkExpression *expression) /* {{{ GtkPropertyExpression */ -typedef struct _GtkPropertyExpression GtkPropertyExpression; - +/** + * GtkPropertyExpression: + * + * A `GObject` property value in a `GtkExpression`. + */ struct _GtkPropertyExpression { GtkExpression parent; @@ -1264,24 +1286,24 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkPropertyExpression, >k_property_expression_info) /** - * gtk_property_expression_new: + * gtk_property_expression_new: (constructor) * @this_type: The type to expect for the this type * @expression: (nullable) (transfer full): Expression to - * evaluate to get the object to query or %NULL to - * query the `this` object + * evaluate to get the object to query or `NULL` to + * query the `this` object * @property_name: name of the property * * Creates an expression that looks up a property via the - * given @expression or the `this` argument when @expression - * is %NULL. + * given `expression` or the `this` argument when `expression` + * is `NULL`. * - * If the resulting object conforms to @this_type, its property - * named @property_name will be queried. - * Otherwise, this expression's evaluation will fail. + * If the resulting object conforms to `this_type`, its property named + * `property_name` will be queried. Otherwise, this expression's + * evaluation will fail. * - * The given @this_type must have a property with @property_name. + * The given `this_type` must have a property with `property_name`. * - * Returns: a new #GtkExpression + * Returns: (type GtkPropertyExpression) (transfer full): a new `GtkExpression` **/ GtkExpression * gtk_property_expression_new (GType this_type, @@ -1318,21 +1340,21 @@ gtk_property_expression_new (GType this_type, } /** - * gtk_property_expression_new_for_pspec: + * gtk_property_expression_new_for_pspec: (constructor) * @expression: (nullable) (transfer full): Expression to - * evaluate to get the object to query or %NULL to - * query the `this` object - * @pspec: the #GParamSpec for the property to query + * evaluate to get the object to query or `NULL` to + * query the `this` object + * @pspec: the `GParamSpec` for the property to query * * Creates an expression that looks up a property via the - * given @expression or the `this` argument when @expression - * is %NULL. + * given `expression` or the `this` argument when `expression` + * is `NULL`. * - * If the resulting object conforms to @this_type, its - * property specified by @pspec will be queried. + * If the resulting object conforms to `this_type`, its + * property specified by `pspec` will be queried. * Otherwise, this expression's evaluation will fail. * - * Returns: a new #GtkExpression + * Returns: (type GtkPropertyExpression) (transfer full): a new `GtkExpression` **/ GtkExpression * gtk_property_expression_new_for_pspec (GtkExpression *expression, @@ -1352,7 +1374,7 @@ gtk_property_expression_new_for_pspec (GtkExpression *expression, /** * gtk_property_expression_get_expression: - * @expression: (type GtkPropertyExpression): a property #GtkExpression + * @expression: (type GtkPropertyExpression): a property `GtkExpression` * * Gets the expression specifying the object of * a property expression. @@ -1371,12 +1393,12 @@ gtk_property_expression_get_expression (GtkExpression *expression) /** * gtk_property_expression_get_pspec: - * @expression: (type GtkPropertyExpression): a property #GtkExpression + * @expression: (type GtkPropertyExpression): a property `GtkExpression` * - * Gets the #GParamSpec specifying the property of + * Gets the `GParamSpec` specifying the property of * a property expression. * - * Returns: (transfer none): the #GParamSpec + * Returns: (transfer none): the `GParamSpec` for the property */ GParamSpec * gtk_property_expression_get_pspec (GtkExpression *expression) @@ -1392,8 +1414,12 @@ gtk_property_expression_get_pspec (GtkExpression *expression) /* {{{ GtkClosureExpression */ -typedef struct _GtkClosureExpression GtkClosureExpression; - +/** + * GtkClosureExpression: + * + * An expression using a custom `GClosure` to compute the value from + * its parameters. + */ struct _GtkClosureExpression { GtkExpression parent; @@ -1580,17 +1606,17 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkClosureExpression, >k_closure_expression_info) /** - * gtk_closure_expression_new: + * gtk_closure_expression_new: (constructor) * @value_type: the type of the value that this expression evaluates to * @closure: closure to call when evaluating this expression. If closure is floating, it is adopted - * @n_params: the number of params needed for evaluating @closure + * @n_params: the number of params needed for evaluating `closure` * @params: (nullable) (array length=n_params) (transfer full): expressions for each parameter * - * Creates a GtkExpression that calls @closure when it is evaluated. - * @closure is called with the @this object and the results of evaluating - * the @params expressions. + * Creates a `GtkExpression` that calls `closure` when it is evaluated. + * `closure` is called with the `this` object and the results of evaluating + * the `params` expressions. * - * Returns: a new #GtkExpression + * Returns: (transfer full) (type GtkClosureExpression): a new `GtkExpression` */ GtkExpression * gtk_closure_expression_new (GType value_type, @@ -1625,8 +1651,11 @@ gtk_closure_expression_new (GType value_type, /* {{{ GtkCClosureExpression */ -typedef struct _GtkCClosureExpression GtkCClosureExpression; - +/** + * GtkCClosureExpression: + * + * A variant of [class@Gtk.ClosureExpression] using a C closure. + */ struct _GtkCClosureExpression { GtkClosureExpression parent; @@ -1649,7 +1678,7 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkCClosureExpression, >k_cclosure_expression_info) /** - * gtk_cclosure_expression_new: + * gtk_cclosure_expression_new: (constructor) * @value_type: the type of the value that this expression evaluates to * @marshal: (scope call) (nullable): marshaller used for creating a closure * @n_params: the number of params needed for evaluating @closure @@ -1658,11 +1687,11 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkCClosureExpression, * @user_data: (nullable): user data used for creating a closure * @user_destroy: (nullable): destroy notify for @user_data * - * This function is a variant of gtk_closure_expression_new() that - * creates a #GClosure by calling g_cclosure_new() with the given - * @callback_func, @user_data and @user_destroy. + * This function is a variant of [ctor@Gtk.ClosureExpression.new] that + * creates a `GClosure` by calling `g_cclosure_new()` with the given + * `callback_func`, `user_data` and `user_destroy`. * - * Returns: a new #GtkExpression + * Returns: (transfer full) (type GtkCClosureExpression): a new `GtkExpression` */ GtkExpression * gtk_cclosure_expression_new (GType value_type, @@ -1707,11 +1736,11 @@ gtk_cclosure_expression_new (GType value_type, /** * gtk_expression_ref: - * @self: (allow-none): a #GtkExpression + * @self: a `GtkExpression` * - * Acquires a reference on the given #GtkExpression. + * Acquires a reference on the given `GtkExpression`. * - * Returns: (transfer none): the #GtkExpression with an additional reference + * Returns: (transfer full): the `GtkExpression` with an additional reference */ GtkExpression * gtk_expression_ref (GtkExpression *self) @@ -1725,11 +1754,11 @@ gtk_expression_ref (GtkExpression *self) /** * gtk_expression_unref: - * @self: (allow-none): a #GtkExpression + * @self: (transfer full): a `GtkExpression` * - * Releases a reference on the given #GtkExpression. + * Releases a reference on the given `GtkExpression`. * - * If the reference was the last, the resources associated to the @self are + * If the reference was the last, the resources associated to the `self` are * freed. */ void @@ -1743,12 +1772,12 @@ gtk_expression_unref (GtkExpression *self) /** * gtk_expression_get_value_type: - * @self: a #GtkExpression + * @self: a `GtkExpression` * - * Gets the #GType that this expression evaluates to. This type + * Gets the `GType` that this expression evaluates to. This type * is constant and will not change over the lifetime of this expression. * - * Returns: The type returned from gtk_expression_evaluate() + * Returns: The type returned from [method@Gtk.Expression.evaluate] **/ GType gtk_expression_get_value_type (GtkExpression *self) @@ -1760,20 +1789,22 @@ gtk_expression_get_value_type (GtkExpression *self) /** * gtk_expression_evaluate: - * @self: a #GtkExpression + * @self: a `GtkExpression` * @this_: (transfer none) (type GObject) (nullable): the this argument for the evaluation - * @value: an empty #GValue + * @value: an empty `GValue` * * Evaluates the given expression and on success stores the result - * in @value. The #GType of @value will be the type given by - * gtk_expression_get_value_type(). + * in @value. + * + * The `GType` of `value` will be the type given by + * [method@Gtk.Expression.get_value_type]. * * It is possible that expressions cannot be evaluated - for example * when the expression references objects that have been destroyed or - * set to %NULL. In that case @value will remain empty and %FALSE + * set to `NULL`. In that case `value` will remain empty and `FALSE` * will be returned. * - * Returns: %TRUE if the expression could be evaluated + * Returns: `TRUE` if the expression could be evaluated **/ gboolean gtk_expression_evaluate (GtkExpression *self, @@ -1789,17 +1820,17 @@ gtk_expression_evaluate (GtkExpression *self, /** * gtk_expression_is_static: - * @self: a #GtkExpression + * @self: a `GtkExpression` * * Checks if the expression is static. * * A static expression will never change its result when - * gtk_expression_evaluate() is called on it with the same arguments. + * [method@Gtk.Expression.evaluate] is called on it with the same arguments. * - * That means a call to gtk_expression_watch() is not necessary because + * That means a call to [method@Gtk.Expression.watch] is not necessary because * it will never trigger a notify. * - * Returns: %TRUE if the expression is static + * Returns: `TRUE` if the expression is static **/ gboolean gtk_expression_is_static (GtkExpression *self) @@ -1840,26 +1871,26 @@ gtk_expression_watch_cb (gpointer data) /** * gtk_expression_watch: - * @self: a #GtkExpression + * @self: a `GtkExpression` * @this_: (transfer none) (type GObject) (nullable): the `this` argument to * watch * @notify: (closure user_data): callback to invoke when the * expression changes - * @user_data: user data to pass to @notify callback - * @user_destroy: destroy notify for @user_data + * @user_data: user data to pass to the `notify` callback + * @user_destroy: destroy notify for `user_data` * - * Installs a watch for the given @expression that calls the @notify function - * whenever the evaluation of @self may have changed. + * Installs a watch for the given `expression` that calls the `notify` function + * whenever the evaluation of `self` may have changed. * * GTK cannot guarantee that the evaluation did indeed change when the @notify * gets invoked, but it guarantees the opposite: When it did in fact change, - * the @notify will be invoked. + * the `notify` will be invoked. * * Returns: (transfer none): The newly installed watch. Note that the only - * reference held to the watch will be released when the watch is unwatched - * which can happen automatically, and not just via - * gtk_expression_watch_unwatch(). You should call gtk_expression_watch_ref() - * if you want to keep the watch around. + * reference held to the watch will be released when the watch is unwatched + * which can happen automatically, and not just via + * [method@Gtk.ExpressionWatch.unwatch]. You should call [method@Gtk.ExpressionWatch.ref] + * if you want to keep the watch around. **/ GtkExpressionWatch * gtk_expression_watch (GtkExpression *self, @@ -1895,11 +1926,11 @@ gtk_expression_watch (GtkExpression *self, /** * gtk_expression_watch_ref: - * @watch: (allow-none): a #GtkExpressionWatch + * @watch: a `GtkExpressionWatch` * - * Acquires a reference on the given #GtkExpressionWatch. + * Acquires a reference on the given `GtkExpressionWatch`. * - * Returns: (transfer none): the #GtkExpression with an additional reference + * Returns: (transfer full): the `GtkExpressionWatch` with an additional reference */ GtkExpressionWatch * gtk_expression_watch_ref (GtkExpressionWatch *watch) @@ -1917,11 +1948,11 @@ gtk_expression_watch_finalize (gpointer data) /** * gtk_expression_watch_unref: - * @watch: (allow-none): a #GtkExpressionWatch + * @watch: (transfer full): a `GtkExpressionWatch` * - * Releases a reference on the given #GtkExpressionWatch. + * Releases a reference on the given `GtkExpressionWatch`. * - * If the reference was the last, the resources associated to @self are + * If the reference was the last, the resources associated to `self` are * freed. */ void @@ -1934,7 +1965,7 @@ gtk_expression_watch_unref (GtkExpressionWatch *watch) * gtk_expression_watch_unwatch: * @watch: (transfer none): watch to release * - * Stops watching an expression that was established via gtk_expression_watch(). + * Stops watching an expression that was established via [method@Gtk.Expression.watch]. **/ void gtk_expression_watch_unwatch (GtkExpressionWatch *watch) @@ -1957,16 +1988,16 @@ gtk_expression_watch_unwatch (GtkExpressionWatch *watch) /** * gtk_expression_watch_evaluate: - * @watch: a #GtkExpressionWatch - * @value: an empty #GValue to be set + * @watch: a `GtkExpressionWatch` + * @value: an empty `GValue` to be set * * Evaluates the watched expression and on success stores the result - * in @value. + * in `value`. * - * This is equivalent to calling gtk_expression_evaluate() with the - * expression and this pointer originally used to create @watch. + * This is equivalent to calling [method@Gtk.Expression.evaluate] with the + * expression and this pointer originally used to create `watch`. * - * Returns: %TRUE if the expression could be evaluated and @value was set + * Returns: `TRUE` if the expression could be evaluated and `value` was set **/ gboolean gtk_expression_watch_evaluate (GtkExpressionWatch *watch, @@ -2072,26 +2103,26 @@ gtk_expression_bind_notify (gpointer data) /** * gtk_expression_bind: - * @self: (transfer full): a #GtkExpression + * @self: (transfer full): a `GtkExpression` * @target: (transfer none) (type GObject): the target object to bind to - * @property: name of the property on @target to bind to + * @property: name of the property on `target` to bind to * @this_: (transfer none) (type GObject) (nullable): the this argument for - * the evaluation of @self + * the evaluation of `self` * - * Bind @target's property named @property to @self. + * Bind `target`'s property named `property` to `self`. * - * The value that @self evaluates to is set via g_object_set() on - * @target. This is repeated whenever @self changes to ensure that - * the object's property stays synchronized with @self. + * The value that `self` evaluates to is set via `g_object_set()` on + * `target`. This is repeated whenever `self` changes to ensure that + * the object's property stays synchronized with `self`. * - * If @self's evaluation fails, @target's @property is not updated. + * If `self`'s evaluation fails, `target`'s `property` is not updated. * You can ensure that this doesn't happen by using a fallback * expression. * - * Note that this function takes ownership of @self. If you want - * to keep it around, you should gtk_expression_ref() it beforehand. + * Note that this function takes ownership of `self`. If you want + * to keep it around, you should [method@Gtk.Expression.ref] it beforehand. * - * Returns: (transfer none): a #GtkExpressionWatch + * Returns: (transfer none): a `GtkExpressionWatch` **/ GtkExpressionWatch * gtk_expression_bind (GtkExpression *self, -- 2.30.2